

<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>The LLVM gold plugin &#8212; LLVM 9 documentation</title>
    <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/language_data.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="LLVM’s Optional Rich Disassembly Output" href="MarkedUpDisassembly.html" />
    <link rel="prev" title="Debugging JIT-ed Code With GDB" href="DebuggingJITedCode.html" />
<style type="text/css">
  table.right { float: right; margin-left: 20px; }
  table.right td { border: 1px solid #ccc; }
</style>

  </head><body>
<div class="logo">
  <a href="index.html">
    <img src="_static/logo.png"
         alt="LLVM Logo" width="250" height="88"/></a>
</div>

    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="MarkedUpDisassembly.html" title="LLVM’s Optional Rich Disassembly Output"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
             accesskey="P">previous</a> |</li>
  <li><a href="http://llvm.org/">LLVM Home</a>&nbsp;|&nbsp;</li>
  <li><a href="index.html">Documentation</a>&raquo;</li>

        <li class="nav-item nav-item-this"><a href="">The LLVM gold plugin</a></li> 
      </ul>
    </div>


    <div class="document">
      <div class="documentwrapper">
          <div class="body" role="main">
            
  <div class="section" id="the-llvm-gold-plugin">
<h1>The LLVM gold plugin<a class="headerlink" href="#the-llvm-gold-plugin" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>Building with link time optimization requires cooperation from
the system linker. LTO support on Linux systems is available via the
<a class="reference external" href="http://sourceware.org/binutils">gold linker</a> which supports LTO via plugins. This is the same mechanism
used by the <a class="reference external" href="http://gcc.gnu.org/wiki/LinkTimeOptimization">GCC LTO</a> project.</p>
<p>The LLVM gold plugin implements the gold plugin interface on top of
<a class="reference internal" href="LinkTimeOptimization.html#liblto"><span class="std std-ref">libLTO</span></a>.  The same plugin can also be used by other tools such as
<code class="docutils literal notranslate"><span class="pre">ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm</span></code>.  Note that ld.bfd from binutils version 2.21.51.0.2
and above also supports LTO via plugins.  However, usage of the LLVM
gold plugin with ld.bfd is not tested and therefore not officially
supported or recommended.</p>
</div>
<div class="section" id="how-to-build-it">
<span id="lto-how-to-build"></span><h2>How to build it<a class="headerlink" href="#how-to-build-it" title="Permalink to this headline">¶</a></h2>
<p>You need to have gold with plugin support and build the LLVMgold plugin.
The gold linker is installed as ld.gold. To see whether gold is the default
on your system, run <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span> <span class="pre">-v</span></code>. It will report “GNU
gold” or else “GNU ld” if not. If gold is already installed at
<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span></code>, one option is to simply make that the default by
backing up your existing <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span></code> and creating a symbolic link
with <code class="docutils literal notranslate"><span class="pre">ln</span> <span class="pre">-s</span> <span class="pre">/usr/bin/ld.gold</span> <span class="pre">/usr/bin/ld</span></code>. Alternatively, you can build
with clang’s <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code> or add <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code> to LDFLAGS, which will
cause the clang driver to invoke <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span></code> directly.</p>
<p>If you have gold installed, check for plugin support by running
<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span> <span class="pre">-plugin</span></code>. If it complains “missing argument” then
you have plugin support. If not, and you get an error such as “unknown option”,
then you will either need to build gold or install a version with plugin
support.</p>
<ul>
<li><p>Download, configure and build gold with plugin support:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git clone --depth <span class="m">1</span> git://sourceware.org/git/binutils-gdb.git binutils
$ mkdir build
$ <span class="nb">cd</span> build
$ ../binutils/configure --enable-gold --enable-plugins --disable-werror
$ make all-gold
</pre></div>
</div>
<p>That should leave you with <code class="docutils literal notranslate"><span class="pre">build/gold/ld-new</span></code> which supports
the <code class="docutils literal notranslate"><span class="pre">-plugin</span></code> option. Running <code class="docutils literal notranslate"><span class="pre">make</span></code> will additionally build
<code class="docutils literal notranslate"><span class="pre">build/binutils/ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm-new</span></code> binaries supporting plugins.</p>
<p>Once you’re ready to switch to using gold, backup your existing
<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span></code> then replace it with <code class="docutils literal notranslate"><span class="pre">ld-new</span></code>. Alternatively, install
in <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span></code> and use <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code> as described earlier.</p>
<p>Optionally, add <code class="docutils literal notranslate"><span class="pre">--enable-gold=default</span></code> to the above configure invocation
to automatically install the newly built gold as the default linker with
<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code>.</p>
</li>
<li><p>Build the LLVMgold plugin. Run CMake with
<code class="docutils literal notranslate"><span class="pre">-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include</span></code>.  The correct include
path will contain the file <code class="docutils literal notranslate"><span class="pre">plugin-api.h</span></code>.</p></li>
</ul>
</div>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>You should produce bitcode files from <code class="docutils literal notranslate"><span class="pre">clang</span></code> with the option
<code class="docutils literal notranslate"><span class="pre">-flto</span></code>. This flag will also cause <code class="docutils literal notranslate"><span class="pre">clang</span></code> to look for the gold plugin in
the <code class="docutils literal notranslate"><span class="pre">lib</span></code> directory under its prefix and pass the <code class="docutils literal notranslate"><span class="pre">-plugin</span></code> option to
<code class="docutils literal notranslate"><span class="pre">ld</span></code>. It will not look for an alternate linker without <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code>,
which is why you otherwise need gold to be the installed system linker in
your path.</p>
<p><code class="docutils literal notranslate"><span class="pre">ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm</span></code> also accept the <code class="docutils literal notranslate"><span class="pre">-plugin</span></code> option and it’s possible to
to install <code class="docutils literal notranslate"><span class="pre">LLVMgold.so</span></code> to <code class="docutils literal notranslate"><span class="pre">/usr/lib/bfd-plugins</span></code> for a seamless setup.
If you built your own gold, be sure to install the <code class="docutils literal notranslate"><span class="pre">ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm-new</span></code> you
built to <code class="docutils literal notranslate"><span class="pre">/usr/bin</span></code>.</p>
<div class="section" id="example-of-link-time-optimization">
<h3>Example of link time optimization<a class="headerlink" href="#example-of-link-time-optimization" title="Permalink to this headline">¶</a></h3>
<p>The following example shows a worked example of the gold plugin mixing LLVM
bitcode and native code.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">---</span> <span class="n">a</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
<span class="cp">#include</span> <span class="cpf">&lt;stdio.h&gt;</span><span class="cp"></span>

<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>

<span class="kt">void</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
  <span class="n">printf</span><span class="p">(</span><span class="s">&quot;Foo2</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
<span class="p">}</span>

<span class="kt">void</span> <span class="nf">foo3</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
  <span class="n">foo4</span><span class="p">();</span>
<span class="p">}</span>

<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
  <span class="n">foo1</span><span class="p">();</span>
<span class="p">}</span>

<span class="o">---</span> <span class="n">b</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
<span class="cp">#include</span> <span class="cpf">&lt;stdio.h&gt;</span><span class="cp"></span>

<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>

<span class="kt">void</span> <span class="nf">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
  <span class="n">foo2</span><span class="p">();</span>
<span class="p">}</span>

<span class="kt">void</span> <span class="nf">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
  <span class="n">printf</span><span class="p">(</span><span class="s">&quot;Foo4&quot;</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>--- <span class="nb">command</span> lines ---
$ clang -flto a.c -c -o a.o      <span class="c1"># &lt;-- a.o is LLVM bitcode file</span>
$ ar q a.a a.o                   <span class="c1"># &lt;-- a.a is an archive with LLVM bitcode</span>
$ clang b.c -c -o b.o            <span class="c1"># &lt;-- b.o is native object file</span>
$ clang -flto a.a b.o -o main    <span class="c1"># &lt;-- link with LLVMgold plugin</span>
</pre></div>
</div>
<p>Gold informs the plugin that foo3 is never referenced outside the IR,
leading LLVM to delete that function. However, unlike in the <a class="reference internal" href="LinkTimeOptimization.html#liblto-example"><span class="std std-ref">libLTO
example</span></a> gold does not currently eliminate foo4.</p>
</div>
</div>
<div class="section" id="quickstart-for-using-lto-with-autotooled-projects">
<h2>Quickstart for using LTO with autotooled projects<a class="headerlink" href="#quickstart-for-using-lto-with-autotooled-projects" title="Permalink to this headline">¶</a></h2>
<p>Once your system <code class="docutils literal notranslate"><span class="pre">ld</span></code>, <code class="docutils literal notranslate"><span class="pre">ar</span></code>, and <code class="docutils literal notranslate"><span class="pre">nm</span></code> all support LLVM bitcode,
everything is in place for an easy to use LTO build of autotooled projects:</p>
<ul>
<li><p>Follow the instructions <a class="reference internal" href="#lto-how-to-build"><span class="std std-ref">on how to build LLVMgold.so</span></a>.</p></li>
<li><p>Install the newly built binutils to <code class="docutils literal notranslate"><span class="pre">$PREFIX</span></code></p></li>
<li><p>Copy <code class="docutils literal notranslate"><span class="pre">Release/lib/LLVMgold.so</span></code> to <code class="docutils literal notranslate"><span class="pre">$PREFIX/lib/bfd-plugins/</span></code></p></li>
<li><p>Set environment variables (<code class="docutils literal notranslate"><span class="pre">$PREFIX</span></code> is where you installed clang and
binutils):</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span> <span class="nv">CC</span><span class="o">=</span><span class="s2">&quot;</span><span class="nv">$PREFIX</span><span class="s2">/bin/clang -flto&quot;</span>
<span class="nb">export</span> <span class="nv">CXX</span><span class="o">=</span><span class="s2">&quot;</span><span class="nv">$PREFIX</span><span class="s2">/bin/clang++ -flto&quot;</span>
<span class="nb">export</span> <span class="nv">AR</span><span class="o">=</span><span class="s2">&quot;</span><span class="nv">$PREFIX</span><span class="s2">/bin/ar&quot;</span>
<span class="nb">export</span> <span class="nv">NM</span><span class="o">=</span><span class="s2">&quot;</span><span class="nv">$PREFIX</span><span class="s2">/bin/nm&quot;</span>
<span class="nb">export</span> <span class="nv">RANLIB</span><span class="o">=</span>/bin/true <span class="c1">#ranlib is not needed, and doesn&#39;t support .bc files in .a</span>
</pre></div>
</div>
</li>
<li><p>Or you can just set your path:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span> <span class="nv">PATH</span><span class="o">=</span><span class="s2">&quot;</span><span class="nv">$PREFIX</span><span class="s2">/bin:</span><span class="nv">$PATH</span><span class="s2">&quot;</span>
<span class="nb">export</span> <span class="nv">CC</span><span class="o">=</span><span class="s2">&quot;clang -flto&quot;</span>
<span class="nb">export</span> <span class="nv">CXX</span><span class="o">=</span><span class="s2">&quot;clang++ -flto&quot;</span>
<span class="nb">export</span> <span class="nv">RANLIB</span><span class="o">=</span>/bin/true
</pre></div>
</div>
</li>
<li><p>Configure and build the project as usual:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>% ./configure <span class="o">&amp;&amp;</span> make <span class="o">&amp;&amp;</span> make check
</pre></div>
</div>
</li>
</ul>
<p>The environment variable settings may work for non-autotooled projects too,
but you may need to set the <code class="docutils literal notranslate"><span class="pre">LD</span></code> environment variable as well.</p>
</div>
<div class="section" id="licensing">
<h2>Licensing<a class="headerlink" href="#licensing" title="Permalink to this headline">¶</a></h2>
<p>Gold is licensed under the GPLv3. LLVMgold uses the interface file
<code class="docutils literal notranslate"><span class="pre">plugin-api.h</span></code> from gold which means that the resulting <code class="docutils literal notranslate"><span class="pre">LLVMgold.so</span></code>
binary is also GPLv3. This can still be used to link non-GPLv3 programs
just as much as gold could without the plugin.</p>
</div>
</div>


            <div class="clearer"></div>
          </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="MarkedUpDisassembly.html" title="LLVM’s Optional Rich Disassembly Output"
             >next</a> |</li>
        <li class="right" >
          <a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
             >previous</a> |</li>
  <li><a href="http://llvm.org/">LLVM Home</a>&nbsp;|&nbsp;</li>
  <li><a href="index.html">Documentation</a>&raquo;</li>

        <li class="nav-item nav-item-this"><a href="">The LLVM gold plugin</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2003-2020, LLVM Project.
      Last updated on 2020-09-20.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
    </div>
  </body>
</html>